Skip to content

feature: dedup por news.content_key no entityCoverage e Article.contentKey (GQL-1b) — só após a migração 035 - #33

Merged
nitaibezerra merged 10 commits into
mainfrom
feature/content-key-dedup
Oct 22, 2026
Merged

nitaibezerra merged 10 commits into
mainfrom
feature/content-key-dedup

Conversation

@nitaibezerra

@nitaibezerra nitaibezerra commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Caution

Ordem de deploy: a migração 035 do data-platform (news.content_key) precisa estar aplicada ANTES do merge.
O merge na main dispara o deploy automaticamente (deploy.yaml, push em src/graphql_api/**), então mergear = colocar no ar.

Estado em 22/10 (conferido em modo somente leitura):

  • 035 aplicada (migration_history id 56, 02:11Z);
  • backfill 036 aplicado (id 58, 04:45–05:09Z): 357.604 artigos, 25.863 com content_key, 12.467 grupos;
  • data-platform#211 (DP-1b, 8bd6b0d) e #212 (DP-1c) na main.
SELECT 1 FROM information_schema.columns WHERE table_name = 'news' AND column_name = 'content_key';

Rede de segurança: se a ordem for outra, o serviço não quebra. O entityCoverage sonda a coluna no catálogo (no máximo a cada 5 min por instância) e, sem ela, usa a chave por hash exato. Sem essa sonda, o _ENTITY_COVERAGE_SQL falharia para todos os clientes, peçam eles uniqueContentCount ou não, porque a janela do dedup é sempre calculada. Cairiam junto os tools get_entity_profile e get_policy_lifecycle do gobus.

Important

Contrato com o DP-1b: mesmo content_hash ⇒ mesma content_key. Em produção ele vale quase sempre, mas não sempre. A correção fica no data-platform (data-platform#213).
O H5 sozinho não garante que hash igual dê chave igual: o E1 exige conteúdo com 30 palavras ou mais e Δt de até 7 dias, e o E2 exige título com 4 tokens ou mais, fora da lista de exclusão. O #211 entrou sem o passo de "unir por content_hash antes do H5".

Medido em produção depois da 036 (somente leitura, 22/10): dos 407 grupos de content_hash repetido (829 artigos), 19 grupos (44 artigos) ficam com 2 chaves efetivas. São 19 contagens a mais no corpus inteiro. Quase todos são recapturas distantes do mesmo órgão (por exemplo, o MDS recapturou em 2026-06-04 matérias de 2023–2025), e numa janela mensal o efeito é de +1 em poucas células.

Decisão (22/10): mergear assim mesmo.

  • O ARTICLE_CONTENT_KEY_SQL do grafo (entity_stats/entity_edges) já está em produção com a mesma expressão. Mergear deixa a API consistente com ele; corrigir só na leitura faria as duas divergirem.
  • O ganho líquido é grande. Exemplo: INSS (Q10302614) de 20/05 a 22/10, com 371 artigos, cai de 370 para 339 conteúdos distintos.
  • Quando o data-platform#213 entrar (união por hash antes do H5, com novo backfill), a API passa a respeitar o contrato sem mudar nada aqui.

Note

Rebase feito (22/10): depois do squash do #32 (ca32127), o branch foi rebaseado com git rebase --onto origin/main dfef051 feature/content-key-dedup. O dfef051 era o head do #32, com árvore idêntica a ca32127. São os mesmos 10 commits, sem conflito e com a árvore final idêntica à de antes do rebase. A base do PR agora é a main.

Resumo (GQL-1b)

O hash exato (content_hash) quase não junta republicações entre órgãos. Cada órgão reescreve as URLs de imagem e de link, então o mesmo texto quase nunca é idêntico byte a byte (Pé-de-Meia 189→189, INSS 371→370). O DP-1b cria news.content_key, a chave de quase-duplicata (regra H5: recall de 92% e precisão de 99% entre órgãos). Este PR troca a chave do lado da API.

  • _CONTENT_DEDUP_KEY_SQL passa a COALESCE(n.content_key, n.content_hash, ne.unique_id).
    • content_key é o unique_id do artigo-líder do grupo.
    • Pelo contrato acima, cada grupo de hash deveria caber inteiro num grupo de chave, e o uniqueContentCount nunca ficaria maior que o do dedup por hash. Hoje há 19 exceções no corpus (data-platform#213).
    • O hash exato só entra em linhas ainda sem chave: antes do backfill, ou recém-ingeridas até a próxima execução da DAG do grafo (a cada 6h).
    • Janela transitória conhecida: um artigo novo sem chave cai no hash, e o gêmeo de hash dele, já com chave, fica com o unique_id do líder. Os dois contam à parte por até 6h.
    • Os espaços de chave não colidem: unique_id do líder contra hash de 16 hex.
    • A API (uniqueContentCount) não muda. É a mesma definição do ARTICLE_CONTENT_KEY_SQL do data-platform, que alimenta entity_stats e entity_edges.
  • Sonda da coluna (_news_has_content_key): desacopla o deploy da ordem da migração.
    • Consulta pg_attribute (attrelid = to_regclass('news')) no máximo a cada 5 min por instância.
    • Sem a coluna, usa _ENTITY_COVERAGE_SQL_SEM_CONTENT_KEY, que é o mesmo SQL com a chave por hash.
    • A 035 aplicada com o serviço no ar entra em uso em até 5 min, sem novo deploy.
    • Se a coluna sumir com a sonda ainda positiva (rollback da 035), o erro 42703 é pego, a query é refeita com a chave por hash e o cache é invalidado. Qualquer outro erro (ou um 42703 no SQL legado) sobe normalmente.
    • Conferido em produção, somente leitura: a sonda devolve false para content_key e true para content_hash.
  • Article.contentKey: String (novo, nulável): a chave de conteúdo efetiva, com a mesma precedência (content_key, depois content_hash, depois unique_id).
    • É calculada em Python (_content_dedup_key) a partir do n.* que o entityArticles já lê. Por isso não exige a coluna: antes da 035, cai no content_hash.
    • Só os caminhos servidos pelo Postgres a preenchem; hoje, o único é entityArticles.
    • Nas listas e na busca servidas pelo Typesense (articles, search, article, relatedArticles etc.) o campo é null, porque o índice ainda não tem a chave.
    • Serve ao "também publicado por: …" do gobus.
  • Descrições do schema: uniqueContentCount e uniqueContentWeight (entity, relatedEntities, entityNetwork, entityCoverage) agora falam em "mesma chave de conteúdo" em vez de "mesmo content_hash". As de entity_stats/entity_edges só ficam exatas depois que a DAG do grafo rodar com o ARTICLE_CONTENT_KEY_SQL novo do DP-1b.
  • Docs: docs/datasources.md explica a ordem com a 035, a sonda, o contrato com o DP-1b e a janela transitória. docs/exemplos.md ganhou um exemplo com contentKey. O SDL de referência foi regenerado.

Schema (diff do SDL)

type Article {
  # ...
  """
  Chave de conteúdo para agrupar republicações: artigos com a mesma chave são o mesmo conteúdo publicado por órgãos diferentes (quase-duplicatas). É a chave do entityCoverage.uniqueContentCount: news.content_key (uniqueId do artigo-líder do grupo); sem ela, o hash exato do conteúdo; sem ele, o próprio uniqueId. Preenchida só nos caminhos servidos pelo Postgres (entityArticles); null nas listas e na busca servidas pelo Typesense, que ainda não indexa a chave.
  """
  contentKey: String
  # ...
}

A mudança é aditiva: nenhum campo ou argumento foi removido ou renomeado. As operações do portal não são afetadas.

Testes

  • pytest: 665 passaram. ruff check src tests: limpo. mkdocs build --strict: ok.
  • TDD red→green em quatro ciclos:
    1. a chave do entityCoverage com a precedência content_key → content_hash → unique_id;
    2. Article.contentKey: quatro casos de fallback, incluindo a linha sem a coluna (antes da 035), mais o entityArticles ponta a ponta pelo schema e o SDL nulável e documentado;
    3. as descrições não prometem mais "mesmo content_hash";
    4. a sonda (tests/datasources/test_postgres_entity_coverage_content_key.py), com estes casos:
      • com a coluna, usa content_key;
      • sem a coluna, usa o hash e não dá erro;
      • uma sonda por TTL;
      • a coluna criada depois entra em uso após o TTL;
      • a coluna removida com o cache positivo leva a refazer pelo hash e invalidar o cache;
      • outros erros sobem;
      • um 42703 no SQL legado sobe;
      • o SQL legado só difere na chave.
  • O SQL novo do entityCoverage foi executado em produção, em modo somente leitura (BEGIN READ ONLY … ROLLBACK), com content_key simulado como NULL (Q155, 01–07/10, granularidade dia). A sintaxe vale e o resultado é igual ao do hash exato, como esperado antes do backfill.

Ordem de deploy

  1. data-platform DP-1b: merge e aplicação da migração 035 (news.content_key TEXT NULL), seguidos do backfill da chave (036) e da tarefa compute_content_keys na DAG do grafo. Tudo isso já está feito (22/10). A união por content_hash antes do H5 fica para o data-platform#213 (ver o bloco IMPORTANT).
  2. Confirmar que a coluna existe (SQL acima).
  3. Rebasear este PR sobre a main, se o feature: rede ego-centrada, lift/articleCount, dateTo exclusivo no entityCoverage, url no ArticleSummary e Flesch pt-BR (GQL-1) #32 já tiver sido mergeado, e mergear: o deploy é automático.
  4. Smoke:
    • log news.content_key presente na revisão nova;
    • entityCoverage(entityId: "Q155", dateFrom: "2026-10-01", dateTo: "2026-10-08", granularity: DAY) sem erro;
    • entityArticles(entityId: "Q155") { articles { uniqueId contentKey } } com contentKey não nulo;
    • gobus_get_entity_profile e gobus_get_policy_lifecycle respondendo.

Rollback

  • Deste PR: reverter o PR. A chave volta para COALESCE(n.content_hash, ne.unique_id) e o contentKey sai do schema. A coluna pode ficar.
  • Da migração 035 (DROP COLUMN): só depois de reverter este PR. O que fica no ar sem a coluna é o entityCoverage, e com ele get_entity_profile e get_policy_lifecycle do gobus.
    • Com a sonda, a ordem inversa não derruba o serviço: a primeira consulta depois do DROP pega o 42703, refaz pela chave por hash e passa a usar o SQL legado.
    • Mesmo assim, a ordem recomendada é reverter este PR antes. Assim nenhuma consulta depende do retry, e os logs não ficam com um warning por instância.
  • O Article.contentKey usa row.get, então não depende da coluna em nenhuma das ordens.

Follow-ups (fora deste PR)

  • data-platform#213: união por content_hash antes do H5, com teste e novo backfill (bloco IMPORTANT). Não bloqueia mais este PR (decisão de 22/10).
  • Indexar content_key no Typesense e trocar o group_by do dedup: true de content_hash para ele. Depois disso, preencher Article.contentKey também nos caminhos do Typesense.
  • gobus: usar contentKey no "também publicado por: …".
  • Revalidar uniqueContentCount das 50 maiores entidades num mês anterior ao defeso, depois do backfill. Conferir também que nenhuma entidade ficou com uniqueContentCount maior que o do dedup por hash.

🤖 Generated with Claude Code

…icle.contentKey e dependência da migração 035
…a coluna (green)

Desacopla o deploy da ordem da migração 035: antes dela (ou depois de um
rollback dela) o entityCoverage usa a chave por hash exato em vez de falhar,
o que derrubaria também get_entity_profile e get_policy_lifecycle do gobus.
A sonda vai ao catálogo no máximo a cada 5 min por instância; um 42703 com
o cache positivo refaz a query pela chave por hash.

Comentário de _CONTENT_DEDUP_KEY_SQL registra o contrato com o DP-1b:
mesmo content_hash implica mesma content_key.
@nitaibezerra
nitaibezerra force-pushed the feature/content-key-dedup branch from 1d67e35 to a2f055d Compare October 22, 2026 05:38
@nitaibezerra
nitaibezerra changed the base branch from feature/rede-ego-lift-url-flesch-ptbr to main October 22, 2026 05:38
@nitaibezerra
nitaibezerra marked this pull request as ready for review October 22, 2026 05:40
@nitaibezerra
nitaibezerra merged commit 6a94bdf into main Oct 22, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant